\documentclass[a4paper,12pt]{article}

\usepackage{fancyhdr}
\usepackage[utf8]{inputenc}
\usepackage{polski}
\usepackage[polish]{babel}
\usepackage{a4wide}

\pagestyle{fancy}

\renewcommand{\headheight}{16pt}

\newcommand{\HRule}{\rule{\linewidth}{0.1mm}}

\begin{document}

\begin{titlepage}
\begin{center}
	\textsc{Inżynieria oprogramowania - Grupa dra inż. Leszka Grocholskiego}\\
	\textsc{II UWr 2009/2010}\\[4cm]

	\HRule \\[2cm]

	Aleksandra Kloc, Adam Grycner, Mateusz Łyczek\\[1cm]

	\textsc{\Large Wasza-fota.pl}\\[0.3cm]
	\textsc{\large Standard kodowania}\\[2cm]

	\HRule\\[2.5cm]
	
\begin{center}
\textbf{Historia zmian tego dokumentu}
\end{center}
\begin{table}[h]
	\begin{center}
	{\footnotesize
	\begin{tabular}{|l|c|p{2.8cm}|l|}
		\hline
		\textbf{Data} & \textbf{Wersja} & \textbf{Autor} & \textbf{Opis zmian}\\
		\hline
		2009/11/18 & 1.0 & Zespół & Utworzenie dokumentu\\
		2009/11/18 & 2.0 & Aleksandra Kloc & Wprowadzenie, Specyfikacja standardu\\
		& & & kodowania w PHP\\
		2009/11/28 & 2.1 & Adam Grycner & Specyfikacja standardu kodowania w Pythonie\\
		\hline
	\end{tabular}
	}
	\end{center}
	\caption{Historia zmian}
\end{table}
	
	
\end{center}
\end{titlepage}

\tableofcontents
\newpage

\section{Wprowadzenie}
W tym dokumencie został przedstawiony standard kodowania, czyli ogólne zasady zapisu składni języka programowania w celu ułatwienia programowania
zespołowego. Wprowadzenie poniższych standardów pomoże również zapewnić wysoką jakość oprogramowania.


\section{Specyfikacja standardu kodowania w Pythonie}
\subsection{Układ kodu}
Wcięcia:
\begin{itemize}
 \item spacje na jeden poziom wcięcia
\end{itemize}
Spacje czy tabulatory:
\begin{itemize}
 \item nigdy nie używa się jednocześnie spacji i tabulatorów jako wcięć w kodzie
\end{itemize}
Maksymalna długość linii:
\begin{itemize}
 \item maksymalnie 79 znaków Preferuje się łamanie linii przez użycie implikowanej kontynuacji linii w nawiasach {}[](), w miarę potrzeby można dodać dodatkową parę nawiasów dookoła długiego wyrażenia. Należy zadbać o właściwe wcięcie kontynuowanej linii. Zaleca się łamać linię po operatorze binarnym, nie przed nim. Przykład:
\end{itemize}
 \begin{verbatim}
def __init__(self, width, height,
        color='black', emphasis=None, highlight=0):
    if width == 0 and height == 0 and \
            color == 'red' and emphasis == 'strong' or \
            highlight > 100:
                raise ValueError("sorry, you lose")
            if width == 0 and height == 0 and (color == 'red' or
                    emphasis is None):
                raise ValueError("I don't think so -- values are %s, %s" %
                        (width, height))
                Blob.__init__(self, width, height,
                        color, emphasis, highlight)
 \end{verbatim}

Puste linie:
\begin{itemize}
 \item należy oddzielać definicje funkcji i klas na najwyższym poziomie dwiema liniami
 \item definicje metod w klasie są oddzielane przez jedną pustą linię
 \item używaj oszczędnie pustych linii do oddzielania logicznych sekcji w funkcji
\end{itemize}

\subsection{Importy}
\begin{itemize}
 \item Importy zwykle umieszcza się w osobnych liniach. Dobrze:
  \begin{verbatim}
      import os
      import sys
  \end{verbatim}
    Źle:
  \begin{verbatim}
      import sys, os
  \end{verbatim}
    ale poniższe jest w porządku:
  \begin{verbatim}
      from subprocess import Popen, PIPE
  \end{verbatim}

  \item Importy umieszcza się u góry pliku, bezpośrednio po komentarzu lub docstringu modułu i przed zmiennymi i stałymi modułuImport powinny być pogrupowane w następującej kolejności: 1. importy z biblioteki standardowej 2. zewnętrzne importy spoza aplikacji 3. import z lokalnej aplikacji/biblioteki. Powinno się umieszczać pustą linię pomiędzy powyższymi trzema grupami importów
  \item Względne importy dla wewnątrz-pakietowych importów są bardzo odradzane, zawsze należy używać pełnej ścieżki pakietu dla wszystkich importów
  \item Podczas importu klas z modułu zawierającego klasy jest w porządku pisać:
  \begin{verbatim}
      from myclass import MyClass
      from foo.bar.yourclass import YourClass
  \end{verbatim}
   lecz jeśli występuje konflikt nazw z lokalnymi klasami należy użyć:
  \begin{verbatim}
      import myclass
      import foo.bar.yourclass
  \end{verbatim}
   i używa się “myclass.MyClass” oraz “foo.bar.yourclass.YourClass”
\end{itemize}

\subsection{Odstępy w wyrażeniach i deklaracjach}
\begin{itemize}
 \item Dobre przykłady:
  \begin{verbatim}
      spam(ham[1], {eggs: 2})
 
      if x == 4: print x, y; x, y = y, x
 
      spam(1)
 
      dict['key'] = list[index]
 
      x = 1
      y = 2
      long_variable = 3
  \end{verbatim}

  \item Pojedyncza spacja po każdej ze stron operatorów: \begin{verbatim}(=), (+=, -= itp.), 
(==, <, >, !=, <>, <=, >=, in, not in, is, is not) i (and, or, not)\end{verbatim}
  \item Spacje dookoła operatorów arytmetycznych:
  \begin{verbatim}
      i = i + 1
      submitted += 1
      x = x * 2 - 1
      hypot2 = x * x + y * y
      c = (a + b) * (a - b)
  \end{verbatim}
   \item brak spacji dookoła znaku = jeśli wskazuje on na domyślny parametr funkcji lub argument.
  \begin{verbatim}
      def complex(real, imag=0.0):
          return magic(r=real, i=imag)
  \end{verbatim}
   
   \item wielokrotne instrukcje na tej samej linii są niewskazane:
  \begin{verbatim}
      if foo == 'blah': do_blah_thing()
      for x in lst: total += x
      wile t &lt; 10: t = delay()
  \end{verbatim}
  Absolutnie nie:
  \begin{verbatim}
      if foo == 'blah': do_blah_thing()
      else: do_non_blah_thing()
 
      try: something()
      finally: cleanup()
 
      do_one(); do_two(); do_three(long, argument,
            list, like, this)
 
      if foo == 'blah': one(); two(); three()
  \end{verbatim}
\end{itemize}

\subsection{Komentarze}
\begin{itemize}
 \item Należy bezwzględnie utrzymywać aktualne komentarze w kodzie. Nieaktualne lub wręcz mylące komentarze są gorsze niż ich brak.
 \item Komentarze powinny być pełnymi zdaniami. Komentarz który jest zdaniem lub frazą powinien mieć pierwsze słowo napisane wielkimi literami, chyba, że jest identyfikatorem rozpoczynającym się małą literą. Nie zmienia się przypadku identyfikatorów.
 \item Kropka na końcu krótkiego komentarza może być pominięta. Blok komentarza na ogół składa się jednego lub więcej paragrafów składających się ze zdań zakończonych kropką.
 \item Należy używać dwóch spacji po kropce kończącej zdanie.
 \item Komentarze zawsze należy pisać po angielsku.
\end{itemize}
Bloki komentarzy.
\begin{itemize}
 \item Bloki komentarzy dotyczą do części (lub całego) kodu, który po nich następuje i powinny mieć takie samo wcięcie jak ów kod. Każda linia kodu zaczyna się ze znaku \# i spacji (\# Komentarz do kodu.).
 \item Paragrafy wewnątrz komentarzy oddzielone są są linią zawierającą tylko jeden znak \#.
\end{itemize}
Komentarze w linii z kodem
\begin{itemize}
 \item Używać oszczędnie
 \item Powinny być oddzielone od instrukcji min. dwiema spacjami.
 \item Nie komentuje się instrukcji oczywistych, np.:
  \begin{verbatim}
      x = x + 1               # increment x by 1
  \end{verbatim}
\end{itemize}
Teksty dokumentacji (Docstrings)
\begin{itemize}
 \item Należy pisać docstringi dla publicznych modułów, funkcji, klas i metod. Docstringi nie są konieczne dla niepublicznych metod lecz powinno się pisać co dana metoda robi. Ten komentarz powinien następować po linii z def.
 \item PEP 257 opisuje poprawne konwencje stosowania docstringów. Przykład:
  \begin{verbatim}
      """Return a foobang
 
      Optional plotz says to frobnicate the bizbaz first.
 
      """
  \end{verbatim} 
  \item Dla docstringu w jednej lini:
  \begin{verbatim}
     """Optional plotz says to frobnicate the bizbaz first."""
  \end{verbatim} 
\end{itemize}




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Specyfikacja standardu kodowania w PHP}

\subsection{Konwencje nazewnicze}

\subsubsection{Ogólne zasady}
Ogólne zasady:
\begin{itemize}
	\item Nazwy powinny określać w sposób jednoznaczny to co nazywają.
	\item Zarówno w przypadku nazw funkcji, zmiennych czy stałych oraz klas stosowane jest nazewnictwo polskie.
	\item Nazwy opisowe nie powinny składać się z więcej niż trzech członów.
\end{itemize}

\subsubsection{Pakiety}
Nazwy pakietów powinny składać się z dużych liter i podkreśleń oddzielających poszczególne ich człony (np. \verb+PAKIET_GLOWNY+).

\subsubsection{Klasy}
Nazwy klas oraz ich człony powinny zaczynać się od dużej litery (np. \verb+PrzykladowaKlasa+). Żaden z członów nie powinien
składać się z dużych liter (nie dotyczy to pierwszych liter członów), nawet gdy jest on skrótem lub powszechnie uznawaną formą zapisu.

\subsubsection{Obiekty i zmienne}
Pierwszy człon nazwy powinien zaczynać się małą literą, a kolejne człony - dużą literą (np. \verb+przykladowaZmiennaObiekt+).
Żaden z członów nie powinien składać się z dużych liter, nawet gdy jest on skrótem lub powszechnie uznawaną formą zapisu
(np. poprawnie - \verb+przykladHtml+, niepoprawnie - \verb+przykladHTML+). Nazwy zmiennych składające się z jednej litery dopuszczalne są tylko
w przypadku iteratorów pętli for.

\subsubsection{Wartości stałe}
Wszystkie człony nazw wartości stałych powinny składać się z dużych liter oraz powinny być połączone podkreśleniami.

\subsubsection{Wartości globalne}
Nazwa wartości globalnych powinna rozpoczynać się od podkreślenia, nazwy pakietu, kolejnego podkreślenia, a następnie właściwej jej nazwy
zapisanej w formie zapisu wartości stałych.

\subsubsection{Funkcje i metody}
Pierwszy człon nazw powinien być pisany z małej litery, a każdy następny z dużej. Dodatkowo nie jest używany znak rozdzielający poszczególne
człony nazw. Nazwy funkcji powinny rozpoczynać się od członu określającego nazwę pakietu, z którego pochodzi dana funkcja.

\subsubsection{Pliki}
Nazwy plików powinny składać się z małych liter oraz określać typ pliku. Np:
\begin{itemize}
	\item \verb+nazwa.class.php+ - plik z klasą modułu,
	\item \verb+nazwa.test.php+ - plik z klasą testową tegoż modułu,
	\item \verb+nazwa.inc.php+ - plik importowany do klasy modułu.
\end{itemize}

\subsection{Organizacja plików}
W nagłówku każdego pliku powinny być zawarte informacje zgodne poniższymi punktami:
\begin{itemize}
	\item Informacje zawiązane z używanym edytorem i jego ustawieniami.
	\item Wersja oprogramowania, dla której pisany był kod.
	\item Nazwa pliku.
	\item Nazwa projektu nadrzędnego.
	\item Krótki opis zadań wykonywanych przez plik.
	\item Opis zmiennych (w szczególności tych, które korzystają z wartości domyślnych)
	\item Nazwy plików niezbędnych
	\item Nazwiska, imiona i adresy e-mail osób, które brały udział w procesie tworzenie pliku.
\end{itemize}

\subsection{Komentarze}
Wszystkie komentarze powinny być zapisane w języku polskim oraz w jasny i prosty sposób opisywać komentowany blok pliku.\\
Rodzaje komentarzy:
\begin{itemize}
	\item \verb+/* Komentarz zajmujący całą linię */+
	\item \verb+Kod();      // Komentarz w tej samej linii co kod programu.+
	\item \begin{verbatim}
		/*
		    Bardzo ważna jedna linia komentarza
		*/
		\end{verbatim}
	\item \begin{verbatim}
		/*
		    Wielowierszowy komentarz.
		    Tutaj już mogą znaleźć się całe zdania.
		*/
		\end{verbatim}
\end{itemize}
Słowa specjalne w komentarzach:
\begin{itemize}
	\item \verb+:TODO:+ - to co pozostało do zrobienia
	\item \verb+:BUG: [ID_bledu]+ - zauważone błędy, wyjaśnienia problemu oraz prawdopodobne przyczyny błędu (ewentualnie nadanie błędowi ID)
	\item \verb+:KLUDGE:+ - jeśli fragment kodu wymaga ulepszenia
	\item \verb+:WARNING:+ - ostrzeżenie przed czymś
\end{itemize}

\subsection{Tagi kodu}
Do oznaczenia kodu PHP powinny być używamy znaczniki:
\begin{verbatim}
        <?php
        ?>
\end{verbatim}
Niedopuszczalne jest korzystanie z wersji krótkiej:
\begin{verbatim}
        <?
        ?>
\end{verbatim}

\subsection{Wcięcia}
Wcięcia powinny składać się z czterech spacji lub znaku tabulacji oznaczającego cztery spacje. Znaczniki kodu PHP powinny znajdywać się w
kolumnie zerowej. Maksymalna długość wiersza to 80 znaków.

\subsection{Nawiasy, spacje i puste linie}
\begin{itemize}
	\item Nawiasy klamrowe \verb+{}+
	\begin{itemize}
		\item Nawiasy klamrowe powinny znajdować się samotnie w nowej linii, chyba, że całe wyrażenie mieści się w jednej linii.
		\item Nawias znajduje się w tej samej kolumnie co pierwsza litera wyrazu wywołującego blok.
	\end{itemize}
	\item Nawiasy \verb+()+ i spacje
	\begin{itemize}
		\item Spację należy wstawić pomiędzy słowami kluczowymi (np. \verb+if+, \verb+while+, \verb+for+, \ldots) oraz nawiasem otwierającym.
		\item W przypadku struktur kontrolnych (takich jak: \verb+if+, \verb+while+, \verb+for+, \ldots) spację należy wstawić pomiędzy
			nawiasem zamykającym oraz nawiasem klamrowym, otwierającym blok, gdy ten znajduje się w tej samej (jednej) linii.
		\item Spacji nie należy wstawiać po nazwach funkcji i metod.
		\item Spacja powinna rozdzielać zmienne oraz argumenty wymieniane po przecinku (np. \verb+function($arg1, $arg2)+).
		\item Spacji nie należy wstawiać po słowie return jeśli nie jest to konieczne.
	\end{itemize}
	\item Pusta linia powinna zostać umieszczona pomiędzy:
	\begin{itemize}
		\item poszczególnymi sekcjami pliku,
		\item definicjami klas i modułów,
		\item metodami i funkcjami,
		\item blokami i komentarzami jednolinijkowymi,
		\item fragmentami metod, które tworzą logiczną całość w celu polepszenia czytelności kodu.
	\end{itemize}
\end{itemize}

\subsection{Dołączanie kodu}
W celu dołączania plików z klasami czy bibliotekami PHP powinna być używana instrukcja \verb+require_once+.

\end{document}
